HTTP Status Codes

HTTP status codes tell you what happened to your API request.
For automation testers, status codes are the first and most important assertion.

This section covers what to validate, why it matters, and common traps.

Why Status Codes Matter

Fast validation: Assert status codes without parsing the response body.
Clear success vs failure signal: Immediate feedback on whether the request succeeded or failed.
Standardized across APIs: Follows RFC standards, making them predictable.
Primary indicator in CI failures: Helps quickly identify issues during pipeline execution.

Golden Rule

Always assert status code before validating response body.

Status Code Categories

Category	Meaning
1xx	Informational (rare)
2xx	Success
3xx	Redirection
4xx	Client errors
5xx	Server errors

Automation focus is mainly on 2xx, 4xx, and 5xx.

✅ 2xx – Success Codes

200 OK

Description: Request processed successfully.
Common for: GET, PUT, PATCH.

Automation Check

Validate that the response body contains expected data.
Example:

Response response = given()
    .when()
    .get("/users/101");

response.then().statusCode(200);
response.then().body("name", equalTo("John"));

201 Created

Description: Resource successfully created.
Common for: POST.

Automation Check

Verify that the response contains the new resource ID.
Validate that the database reflects the creation.

Real-World Example

Creating a user:

POST /users
Body:
{
  "name": "John",
  "email": "john@example.com"
}

Response:

{
  "id": 101,
  "name": "John",
  "email": "john@example.com"
}

Code Snippet

Response response = given()
    .header("Content-Type", "application/json")
    .body("{ "name": "John", "email": "john@example.com" }")
    .when()
    .post("/users");

response.then().statusCode(201);
response.then().body("id", notNullValue());

204 No Content

Description: Success with no response body.
Common for: DELETE.

Automation Check

Ensure the response body is empty.
Validate side effects (e.g., resource removed from the database).

Real-World Example

Deleting a user:

DELETE /users/101

Code Snippet

Response response = given()
    .when()
    .delete("/users/101");

response.then().statusCode(204);
response.then().body(equalTo(""));

❌ 4xx – Client Error Codes

Client sent an invalid request.

400 Bad Request

Description: Invalid input, missing fields, or invalid format.
Tester Use: Negative testing, input validation checks.

Real-World Example

Invalid email format:

POST /users
Body:
{
  "name": "John",
  "email": "invalid-email"
}

Response:

{
  "error": "Invalid email format"
}

Code Snippet

Response response = given()
    .header("Content-Type", "application/json")
    .body("{ "name": "John", "email": "invalid-email" }")
    .when()
    .post("/users");

response.then().statusCode(400);
response.then().body("error", equalTo("Invalid email format"));

401 Unauthorized

Description: Missing or invalid authentication.
Tester Check: Token missing/expired, correct auth mechanism used.

Real-World Example

Missing token:

GET /users/101
Headers:
Authorization: Bearer <missing>

Response:

{
  "error": "Unauthorized"
}

403 Forbidden

Description: Authenticated but no permission.
Tester Insight: Role-based access issue.

Real-World Example

Non-admin user trying to delete a resource:

DELETE /admin/users/101
Headers:
Authorization: Bearer <user-token>

Response:

{
  "error": "Forbidden"
}

404 Not Found

Description: Resource does not exist.
Tester Use: Invalid ID scenarios, delete validation.

Real-World Example

Fetching a non-existent user:

GET /users/999

Response:

{
  "error": "User not found"
}

409 Conflict

Description: Duplicate data or resource state conflict.
Common in: Duplicate POST, idempotency issues.

Real-World Example

Duplicate user creation:

POST /users
Body:
{
  "email": "john@example.com"
}

Response:

{
  "error": "Email already exists"
}

💥 5xx – Server Error Codes

Server failed to process a valid request.

500 Internal Server Error

Description: Unhandled exception, backend bug.
Tester Action: Capture request/response, report as backend defect.

Real-World Example

Unexpected server crash:

GET /users/101

Response:

{
  "error": "Internal Server Error"
}

502 Bad Gateway

Description: Upstream service failure.
Common in: Microservices, downstream dependency issues.

Real-World Example

Payment gateway down:

POST /payments

Response:

{
  "error": "Bad Gateway"
}

503 Service Unavailable

Description: Server overloaded or down.
Tester Insight: Infra issue, not functional bug.

Real-World Example

High traffic causing downtime:

GET /orders

Response:

{
  "error": "Service Unavailable"
}

Status Codes vs Automation Decisions

Code	Test Result
Expected 2xx	PASS
Expected 4xx	PASS (negative case)
Unexpected 4xx	FAIL
Any 5xx	FAIL